<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>libdoc.py</title>
<style type="text/css">

/* Robot Framework User Guide Style Sheet

   This stylesheet contains styles from restructuredText's default 
   'html4css1.css' and after that modifications needed for Robot Framework User
   Guide. These styles are added into the same file against suggestions at 
   reST's stylesheet  howto mentioned below, because we want to be able to 
   embed all styles into the created HTML file. Everything before 'Robot 
   Framework User Guide Modifications' text is from 'html4css1.css' without 
   any changes so that part can still be changed easily.
*/


/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }


/* **************************************** *
 * Robot Framework User Guide Modifications * 
 * **************************************** */

/* Tables
   - example, tsv-example: test data examples
   - messages: log message examples
   - tabular: normal tabular information
*/
table.example, table.tsv-example, table.messages, table.tabular {
    border: 1px solid #808080;
    border-collapse: collapse;
    empty-cell: show;
    margin: 0.5em 2em;
}
table.example caption, table.tsv-example caption, table.tabular caption {
    text-align: left;
    padding-bottom: 0.5em;
    font-style: italic;
    font-size: 0.9em;
    width: 100%;
}
table.example th, table.example td, table.tsv-example td {
    border: 1px solid #808080;
    font-family: arial,helvetica,sans-serif;
    height: 1.2em;
    font-size: 0.8em;
}
table.example th {
    padding: 0.1em 1em;
    background: #E0E0E0;
}
table.example td, table.tsv-example td {
    padding: 0.1em 1em 0.1em 0.3em;
}
table.tabular th, table.tabular td {
    border: 1px solid black;
    padding: 0.1em 0.3em;
    height: 1.2em;
    font-size: 0.8em;
}
table.messages {
    border: 1px solid gray;
    font-family: monospace;
    margin: 1em 2em;
    width: 60%;
}
table.messages td {
    vertical-align: top;
    padding: 0.1em 0.2em;
}
table.messages td.time {
    width: 7em;
    letter-spacing: -0.05em;
} 
table.messages td.level {
    width: 5em;
    text-align: center;
}
table.messages td.fail, table.messages td.error {
    color: red;
}
table.messages td.pass {
    color: #009900;
}
table.messages td.warn {
    color: #FFCC00;
}

/* Roles -- these are defined in roles.txt file */

.var {
    background: #f4f4f4;
    font-size: 0.9em;
}
.opt {
    font-style: italic;
}
.prog, .code, .cli {
    background: #f4f4f4;
    font-family: monospace;
}
.msg {
    font-family: monospace;
}
.name {  
    font-style: italic;
}
.path {
    font-style: italic;
}
.misc, .literal {
    background: #f4f4f4;
}


/* Overridden and modified styles */

cite {
    font-size: 0.95em;
}
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
    border: 0.1em solid gray;
    margin: 1em 2em;
    padding: 0.7em 1em;
    font-size: 0.9em;
}
pre.literal-block, pre.doctest-block {
    background: #f4f4f4;
}
li, li p.first {
    margin-top: 0.3em;
    margin-bottom: 0.3em;
}
div.contents li {
    margin-top: 0em;
    margin-bottom: 0em;
}


/* Pygments 

- Styles generated using "HtmlFormatter().get_style_defs('.highlight')"
- Changed only background (f8f8f8 -> f4f4f4) and added margin
- For more details see e.g. http://pygments.org/docs/quickstart/
*/

.highlight  { background: #f4f4f4; margin: 1em 2em; }
.highlight .c { color: #408080; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #008000; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #808080 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0040D0 } /* Generic.Traceback */
.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.highlight .kp { color: #008000 } /* Keyword.Pseudo */
.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #B00040 } /* Keyword.Type */
.highlight .m { color: #666666 } /* Literal.Number */
.highlight .s { color: #BA2121 } /* Literal.String */
.highlight .na { color: #7D9029 } /* Name.Attribute */
.highlight .nb { color: #008000 } /* Name.Builtin */
.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.highlight .no { color: #880000 } /* Name.Constant */
.highlight .nd { color: #AA22FF } /* Name.Decorator */
.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0000FF } /* Name.Function */
.highlight .nl { color: #A0A000 } /* Name.Label */
.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #19177C } /* Name.Variable */
.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mf { color: #666666 } /* Literal.Number.Float */
.highlight .mh { color: #666666 } /* Literal.Number.Hex */
.highlight .mi { color: #666666 } /* Literal.Number.Integer */
.highlight .mo { color: #666666 } /* Literal.Number.Oct */
.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
.highlight .sc { color: #BA2121 } /* Literal.String.Char */
.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
.highlight .ss { color: #19177C } /* Literal.String.Symbol */
.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
.highlight .vc { color: #19177C } /* Name.Variable.Class */
.highlight .vg { color: #19177C } /* Name.Variable.Global */
.highlight .vi { color: #19177C } /* Name.Variable.Instance */
.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */

</style>
</head>
<body>
<div class="document" id="libdoc-py">
<h1 class="title">libdoc.py</h1>

<!-- Roles to use in text like :rolename:`text`. Styled in userguide.css.
- var    variables
- opt    settings in setting table (e.g. Force Tags), tc/kw tables
         (e.g [Documentation]) and command line options (e.g. - -name)
- prog   program names (e.g. rebot, risto.py)
- code   programming code
- msg    test case status and message, as well as log messages and levels
- name   keyword, library, test case, test suite, etc. names
- cli    command line examples (note that options alone use opt)
- path   file names and paths
- misc   everything else (synonym to ``text``) -->
<p><span class="prog">libdoc.py</span> is a tool for generating keyword documentation for test
libraries and resource files in HTML and XML formats. Documentation can be
created for both test libraries and resource files. Starting from
Robot Framework 2.1.2 it is also possible to upload documentation to <a class="reference external" href="http://code.google.com/p/rfdoc">RFDoc</a> service.</p>
<p><span class="prog">libdoc.py</span> is included in source distributions and can also be downloaded
from <a class="reference external" href="http://code.google.com/p/robotframework/wiki/LibraryDocumentationTool">http://code.google.com/p/robotframework/wiki/LibraryDocumentationTool</a>.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#synopsis" id="id4">Synopsis</a></li>
<li><a class="reference internal" href="#options" id="id5">Options</a></li>
<li><a class="reference internal" href="#description" id="id6">Description</a><ul>
<li><a class="reference internal" href="#specifying-the-library-or-resource-file" id="id7">Specifying the library or resource file</a></li>
<li><a class="reference internal" href="#uploading-documentation" id="id8">Uploading documentation</a></li>
<li><a class="reference internal" href="#examples" id="id9">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-documentation" id="id10">Writing documentation</a><ul>
<li><a class="reference internal" href="#python-libraries" id="id11">Python libraries</a></li>
<li><a class="reference internal" href="#java-libraries" id="id12">Java libraries</a></li>
<li><a class="reference internal" href="#dynamic-libraries" id="id13">Dynamic libraries</a></li>
<li><a class="reference internal" href="#importing-section" id="id14">Importing section</a></li>
<li><a class="reference internal" href="#resource-files" id="id15">Resource files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#documentation-syntax" id="id16">Documentation syntax</a><ul>
<li><a class="reference internal" href="#generic-formatting-rules" id="id17">Generic formatting rules</a></li>
<li><a class="reference internal" href="#special-formatting-and-internal-linking" id="id18">Special formatting and internal linking</a></li>
<li><a class="reference internal" href="#keywords-arguments" id="id19">Keywords' arguments</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="synopsis">
<h1><a class="toc-backref" href="#id4">Synopsis</a></h1>
<pre class="literal-block">
libdoc.py [options] library_or_resource_file
</pre>
</div>
<div class="section" id="options">
<h1><a class="toc-backref" href="#id5">Options</a></h1>
<blockquote>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-a</span>, <span class="option">--argument <var>&lt;value&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Possible arguments that a library needs.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-f</span>, <span class="option">--format <var>&lt;html|xml&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Specifies whether to generate HTML or XML output.
Since 2.1.2 version the default value is got from
the output file extension. With earlier versions,
or if the output is not specified, the default is HTML.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-o</span>, <span class="option">--output <var>&lt;path&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Either a directory or a file where to write the generated
documentation or a URL where to upload it. If a path
pointing to a directory is used, the documentation is
written there using a name like <cite>&lt;name&gt;.&lt;format&gt;</cite>. If
a file with that name already exists, an index is added
after the <cite>&lt;name&gt;</cite> part.
If the path starts with <cite>http://</cite>, it is assumed to
be a URL to RFDoc's upload page and the documentation
is uploaded there.
Otherwise the path is used directly as a file name and
possible existing files are overwritten.
The default value for the path is the directory
where the script is executed from.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-N</span>, <span class="option">--name <var>&lt;newname&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the name of the documented library or resource.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-T</span>, <span class="option">--title <var>&lt;title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the title of the generated HTML documentation.
Underscores in the given title are automatically
converted to spaces.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-S</span>, <span class="option">--styles <var>&lt;styles&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Overrides the default styles. If the given <cite>styles</cite>
is a path to an existing files, styles will be read
from it. If it is string <cite>NONE</cite>, no styles will be
used. Otherwise the given text is used as-is.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-P</span>, <span class="option">--pythonpath <var>&lt;path&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Additional path(s) to insert into PYTHONPATH.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-E</span>, <span class="option">--escape <var>&lt;what:with&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Escapes characters which are problematic in console.
<span class="opt">what</span> is the name of the character to escape
and <span class="opt">with</span> is the string to escape it with.
Available escapes are listed in the <span class="opt">--help</span>
output.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>Prints this help.</td></tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="description">
<h1><a class="toc-backref" href="#id6">Description</a></h1>
<p><span class="prog">libdoc.py</span> is a tool for generating keyword documentation for test
libraries and resource files in HTML and XML formats. The former format is
suitable for humans and the latter for <a class="reference external" href="http://code.google.com/p/robotframework-ride">RIDE</a>, <a class="reference external" href="http://code.google.com/p/rfdoc">RFDoc</a> and other tools.
It is even possible to upload the XML documentation to RFDoc systems.</p>
<p>Documentation can be created for:</p>
<ul class="simple">
<li>Test libraries implemented with <a class="reference internal" href="#python-libraries">Python</a> or <a class="reference internal" href="#java-libraries">Java</a> using the normal library API</li>
<li>Test libraries using the <a class="reference internal" href="#dynamic-libraries">dynamic API</a></li>
<li><a class="reference internal" href="#resource-files">Resource files</a></li>
</ul>
<p>Additionally it is possible to use XML documentation created earlier by
<cite>libdoc.py</cite> or other tools as input. This allows uploading these XML documents
to RFDoc and generating stand-alone HTML documentation from them.</p>
<div class="section" id="specifying-the-library-or-resource-file">
<h2><a class="toc-backref" href="#id7">Specifying the library or resource file</a></h2>
<p>It is possible to specify a Python test library by giving either the
path to the source or only the library name. If the library name is
used, it must be in the same format as in the Robot Framework test
data when importing libraries. In this case, the library is searched
from PYTHONPATH (and from CLASSPATH, if on Jython).</p>
<p>A Java test library implemented with a normal library API can be
specified by giving the path to the source code file containing the
library implementation. Additionally, <span class="path">tools.jar</span>, which is part
of the Sun JDK distribution, must be found from CLASSPATH when
<span class="prog">libdoc.py</span> is executed. When generating documentation for Java
libraries, <span class="prog">libdoc.py</span> must be executed using Jython.</p>
<p>Libraries using the dynamic library API are handled in the same way as Python
libraries.</p>
<p>Some libraries require arguments when they are imported and they can be given
using <span class="opt">--argument</span> option. It can be used multiple times to specify multiple
arguments. Libraries always get these arguments as strings. If
arguments change what keywords the library provides or otherwise
change its behavior, it might be a good idea to use <span class="opt">--name</span>
option to also change the library name accordingly.</p>
<p>Resource files must always be specified using a path. If the path does not
exist, resource files are also searched from all directories in PYTHONPATH.</p>
</div>
<div class="section" id="uploading-documentation">
<h2><a class="toc-backref" href="#id8">Uploading documentation</a></h2>
<p>Uploading the generated documentation to RFDoc is as easy as specifying the URL
to the RFDoc upload page using <span class="opt">--output</span> option. This URL must always
start with <cite>http://</cite>. It is possible to upload all documentations to RFDoc
and input can also be an earlier created XML documentation.</p>
</div>
<div class="section" id="examples">
<h2><a class="toc-backref" href="#id9">Examples</a></h2>
<pre class="literal-block">
python libdoc.py OperatingSystem
python libdoc.py --output doc/MyLib.html src/MyLib.py
python libdoc.py --argument arg1 --argument arg2 LibraryWithArgs.py
python libdoc.py --name MyLibrary --argument 10.0.0.42:8270 Remote.py
python libdoc.py test/resource.html
python libdoc.py --format xml OperatingSystem
python libdoc.py --format xml --output doc test/resource.html
jython libdoc.py --output MyJavaLibrary.xml MyJavaLibrary.java
python libdoc.py --output http://rfdoc.mydomain/upload MyLibrary
python libdoc.py --output http://rfdoc.mydomain/upload specs/Lib.xml
</pre>
</div>
</div>
<div class="section" id="writing-documentation">
<h1><a class="toc-backref" href="#id10">Writing documentation</a></h1>
<p>For more information about how to actually create test libraries and resource
files see <a class="reference external" href="http://code.google.com/p/robotframework/wiki/UserGuide">Robot Framework User Guide</a>.</p>
<div class="section" id="python-libraries">
<h2><a class="toc-backref" href="#id11">Python libraries</a></h2>
<p>The documentation for Python libraries is written simply as doc
strings for the library class and for methods implementing
keywords. The first line of the method documentation is considered as
a short documentation for the keywords (used for example as a tool tip in
links in the generated HTML documentation), and it should thus be as
describing as possible, but not too long.</p>
<p>The simple example below illustrates how to write the documentation,
and for example <a class="reference external" href="http://code.google.com/p/robotframework/wiki/TestLibraries">standard libraries</a> give more
realistic examples. For more information on Python documentation
strings, see <a class="reference external" href="http://www.python.org/dev/peps/pep-0257">PEP-257</a>.</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">ExampleLib</span><span class="p">:</span>
    <span class="sd">&quot;&quot;&quot;Library for demo purposes.</span>

<span class="sd">    This library is only used in an example and it does&#39;t do anything useful.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="nf">my_keyword</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;Does nothing.&quot;&quot;&quot;</span>
        <span class="k">pass</span>

    <span class="k">def</span> <span class="nf">your_keyword</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;Takes one argument and *does nothing* with it.</span>

<span class="sd">        Example:</span>
<span class="sd">        | Your Keyword | xxx |</span>
<span class="sd">        | Your Keyword | yyy |</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>
</pre></div>
</div>
<div class="section" id="java-libraries">
<h2><a class="toc-backref" href="#id12">Java libraries</a></h2>
<p>When writing documentation for a normal Java library, conventions for
writing Javadoc should be used. The documentation is generated based
on the Javadocs in the source files. For example following simple
example has exactly same documentation (and functionality) than the
earlier Python example.</p>
<div class="highlight"><pre><span class="cm">/**</span>
<span class="cm"> * Library for demo purposes.</span>
<span class="cm"> *</span>
<span class="cm"> * This library is only used in an example and it does&#39;t do anything useful.</span>
<span class="cm"> */</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ExampleLib</span> <span class="o">{</span>

    <span class="cm">/**</span>
<span class="cm">     * Does nothing</span>
<span class="cm">     */</span>
    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">myKeyword</span><span class="o">()</span> <span class="o">{</span>
    <span class="o">}</span>

    <span class="cm">/**</span>
<span class="cm">     * Takes one argument and *does nothing* with it.</span>
<span class="cm">     *</span>
<span class="cm">     * Example:</span>
<span class="cm">     * | Your Keyword | xxx |</span>
<span class="cm">     * | Your Keyword | yyy |</span>
<span class="cm">     */</span>
    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">yourKeyword</span><span class="o">(</span><span class="n">String</span> <span class="n">arg</span><span class="o">)</span> <span class="o">{</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<div class="section" id="dynamic-libraries">
<h2><a class="toc-backref" href="#id13">Dynamic libraries</a></h2>
<p>To be able to generate meaningful documentation for dynamic libraries,
they must return keyword argument names and documentation using
<span class="code">get_keyword_arguments</span> and <span class="code">get_keyword_documentation</span>
methods (or using their camelCase variants <span class="code">getKeywordArguments</span>
and <span class="code">getKeywordDocumentation</span>). See the <a class="reference external" href="http://code.google.com/p/robotframework/wiki/UserGuide">User Guide</a> for more
information about how to create these methods and the dynamic library
API in general.</p>
</div>
<div class="section" id="importing-section">
<h2><a class="toc-backref" href="#id14">Importing section</a></h2>
<p>A separate section about how the library is imported is created based on its
initialization methods. For a Python library, if it has an  <span class="code">__init__</span> method
that takes arguments in addition to <span class="code">self</span>, the documentation of that
method is shown. For a Java library, if it has a constructor that accepts
arguments, all its constructors and their javadocs are shown.</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">TestLibrary</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s">&#39;default&#39;</span><span class="p">)</span>
        <span class="sd">&quot;&quot;&quot;Creates new TestLibrary. `mode` argument is used to determine mode.&quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">mode</span> <span class="o">=</span> <span class="n">mode</span>

    <span class="k">def</span> <span class="nf">some_keyword</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">mode</span> <span class="o">==</span> <span class="s">&#39;secret&#39;</span><span class="p">:</span>
             <span class="c"># ...</span>
</pre></div>
</div>
<div class="section" id="resource-files">
<h2><a class="toc-backref" href="#id15">Resource files</a></h2>
<p>Keywords in resource files can have documentation using
<span class="opt">[Documentation]</span> setting, and this documentation is also used by
<span class="prog">libdoc.py</span>. First line of the documentation (until the first
<span class="code">\n</span>) is considered to be the short documentation similarly as
with test libraries.</p>
<p>Starting from Robot Framework 2.1 also the resource file itself can
have <span class="opt">Documentation</span> in the Setting table for documenting the whole resource file.</p>
<p>Possible variables in resource files are not documented.</p>
<table border="1" class="example docutils">
<caption>An example resource file</caption>
<colgroup>
<col width="17%" />
<col width="46%" />
<col width="38%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Documentation</td>
<td>Resource file for demo purposes.\n</td>
<td>&nbsp;</td>
</tr>
<tr><td>...</td>
<td>This resource is only used in an example</td>
<td>and it does't do anything useful.</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="16%" />
<col width="21%" />
<col width="28%" />
<col width="36%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>My Keyword</td>
<td>[Documentation]</td>
<td>Does nothing</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Your Keyword</td>
<td>[Arguments]</td>
<td>${arg}</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>[Documentation]</td>
<td>Takes one argument and
*does nothing* with
it.\n</td>
<td><div class="first last line-block">
<div class="line">Example:\n</div>
<div class="line">| Your Keyword | xxx |\n</div>
<div class="line">| Your Keyword | yyy |\n</div>
</div>
</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="documentation-syntax">
<h1><a class="toc-backref" href="#id16">Documentation syntax</a></h1>
<div class="section" id="generic-formatting-rules">
<h2><a class="toc-backref" href="#id17">Generic formatting rules</a></h2>
<p>The <a class="reference external" href="http://code.google.com/p/robotframework/wiki/UserGuide">User Guide</a> has an appendix explaining different documentation
formatting possibilities supported by Robot Framework.
Most important features are formatting using
<span class="code">*bold*</span> and <span class="code">_italic_</span>, automatic conversion of URLs to
clickable links, and the possibility to create tables (useful for
examples) simply with pipe character:</p>
<pre class="literal-block">
| Some Keyword    | arg |
| Another Keyword |     |
</pre>
</div>
<div class="section" id="special-formatting-and-internal-linking">
<h2><a class="toc-backref" href="#id18">Special formatting and internal linking</a></h2>
<p>In addition to the formatting explained in the User Guide,
<span class="prog">libdoc.py</span> supports also special formatting of keyword names
and arguments with backtick character <span class="code">`</span>. Even more
importantly, this syntax also automatically creates internal links to
other keywords in the library. For example documentation of the
following simple Python library would have link from <span class="name">Log
Messages</span> to <span class="name">Log Message</span>, and <span class="code">`message`</span> and
<span class="code">`level`</span> would be formatted specially.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">log_message</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="s">&quot;INFO&quot;</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Writes given message to log using specified log level.</span>

<span class="sd">    `message` can be any object. Valid values for `level` are &quot;INFO&quot; (default),</span>
<span class="sd">    &quot;DEBUG&quot; and &quot;TRACE&quot;.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">print</span> <span class="s">&quot;*</span><span class="si">%s</span><span class="s">* </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">level</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">log_messages</span><span class="p">(</span><span class="n">message1</span><span class="p">,</span> <span class="n">message2</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="s">&quot;INFO&quot;</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Writes given messages to log using specified log level.</span>

<span class="sd">    See `Log Message` keyword for more information about valid values</span>
<span class="sd">    for `level`.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">log_message</span><span class="p">(</span><span class="n">message1</span><span class="p">,</span> <span class="n">level</span><span class="p">)</span>
    <span class="n">log_message</span><span class="p">(</span><span class="n">message2</span><span class="p">,</span> <span class="n">level</span><span class="p">)</span>
</pre></div>
<p>Additionally, using <span class="code">`introduction`</span> or <span class="code">`library introduction`</span>
(case insensitive) generates a link to the library introduction in the beginning
of the generated documentation. Similarly <span class="code">`importing`</span>
or <span class="code">`library importing`</span> generates a link to the <a class="reference internal" href="#importing-section">importing section</a>.</p>
<p>Internal linking between keywords is used by all <a class="reference external" href="http://code.google.com/p/robotframework/wiki/TestLibraries">standard
libraries</a>, so their documentation (and source) acts as a more
realistic example.</p>
</div>
<div class="section" id="keywords-arguments">
<h2><a class="toc-backref" href="#id19">Keywords' arguments</a></h2>
<p><span class="prog">libdoc.py</span> handles keywords' arguments automatically so that
arguments specified for methods in libraries or user keywords in
resource files are listed in a separate column. Possible trailing
underscores in argument names are stripped to make it possible to use
arguments like <span class="code">list_</span> in the code and still have <span class="code">list</span>
in documentation. Additionally, user keyword arguments are shown
without <span class="var">${}</span> or <span class="var">&#64;{}</span> to make arguments look the same
regardless where keywords originated from.</p>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2010-04-16 22:28 UTC.

</div>
</body>
</html>
